<section>
    <h1 class="blue" data-id="#custom/onpage-help"><i class="ace-icon fa fa-desktop grey"></i> Onpage Help</h1>


    <div class="alert alert-info">
        <button class="close" data-dismiss="alert"><i class="ace-icon fa fa-times"></i></button>
        <i class="ace-icon fa fa-exclamation-triangle"></i>
        Please use the following info and demo's example to use Onpage Help in your own app.
        <br/>
        It still may be confusing though, so if you need further help with that, just get in touch with me.
    </div>

    <div class="hr hr-double hr32"></div>

    <!-- #section:custom/onpage-help -->
    <div class="help-content">
        <h3 class="info-title smaller">1. Overview</h3>

        <div class="info-section">
            <ul class="info-list list-unstyled">
                <li>
                    Onpage Help is a feature of Ace admin template that allows users
                    to select an element or a section of a page and see more info about it without leaving the page.
                    <br/>
                    For an example of this you can refer to
                    <a href="../html/index.html#help">Ace demo</a>
                    and click the black button on right of page.
                </li>

                <li>
                    You can also use this feature in your app to provide help and instructions for users.
                </li>
            </ul>
        </div>


        <h3 class="info-title smaller">2. Usage</h3>

        <div class="info-section">
            <ul class="info-list list-unstyled">
                <li>
                    Help content can be retrieved from your own help files and it will be displayed inside a modal box
                    in your
                    application.
                </li>

                <li>
                    To use onpage help you should build a custom Javascript file using JS builder tool and include
                    onpage help feature or you can directly include
                    <code>assets/js/ace/elements.onpage-help.js</code> file.
                </li>

                <li>
                    To initiate help you can call:
<pre data-language="javascript">
jQuery(function($) {
  var help = new Onpage_Help({/* for available options, see below */});
  $('#some-button').on('click', function() {
	help.toggle();
	//or help.enable()
	//or help.disable()
  })
})
</pre>
                </li>

                <li>
                    Your application page should have special comments for special sections that have help material:
<pre data-language="html">
 <!-- #section:manage/user -->
  Some elements are here which will show a help dialog when clicked!
 <!-- /section:manage/user -->
</pre>
                </li>

                <li>
                    The help content is retrieved dynamically from a remote file that you specify.
                    <br/>
                    That file should have similar comments like above:
<pre data-language="html">
 <!-- #section:manage/user -->
  Documentation and help content for "manage/user" are here inside some file.
 <!-- /section:manage/user -->
</pre>
                    <br/>
                    There should also be an element with <code>data-id="#manage/user"</code> attribute
                    which is used to specify modal box's title.
                    <br/>
                    If no such element exists, its possible parent is looked up and if available its title is used for
                    the modal box!
                </li>

                <li>
                    If inside one documentation(help) page, there are several sections to be displayed in your
                    application,
                    you should use "."(dot) character to separate them:
<pre data-language="html">
 <!-- #section:manage/user.edit -->
  Manage user documentation is here
 <!-- /section:manage/user.edit -->
..
..
..
 <!-- #section:manage/user.delete -->
  Delete user documentation is here
 <!-- /section:manage/user.delete -->
</pre>
                </li>

                <li>
                    Same is true for your application page:
<pre data-language="html">
 <!-- #section:manage/user.edit -->
  <a href="#">Edit</a><!-- will display help dialog -->
 <!-- /section:manage/user.edit -->
..
..
..
 <!-- #section:manage/user.delete -->
   <a href="#">Delete</a><!-- will display help dialog -->
 <!-- /section:manage/user.delete -->
</pre>
                </li>

                <li>
                    When user clicks on a help section to see its content, the name of section is passed
                    to "section_url" function in which you should return the url which contains relevant help material.
                    <br/>
                    Please see next section for more info.
                </li>

                <li>
                    If you have files with HTML, CSS, etc code that you want to show inside the modal help dialog,
                    you can wrap the path inside a <code>code</code> tag with <code>.open-file</code> class
                    and <code>data-open-file="css"</code> attribute:
<pre data-language="html">
 <code class="open-file" data-open-file="js">path/to/some/file.js</code>
</pre>
                </li>

            </ul>
        </div>


        <h3 class="info-title smaller">3. Options</h3>

        <div class="info-section">
            <ul class="info-list list-unstyled">
                <li>
                    There are several options when initiating help.
                </li>
                <li><code>icon_1</code> Optional icon displayed inside a help section.
                    Default is 'fa fa-question'
                    <br/>
				<span class="thumbnail inline">
					<img src="images/help-icon1.png"/>
				</span>
                </li>
                <li><code>icon_2</code> Optional icon displayed on top left of a help section.
                    Default is 'fa fa-lightbulb-o'
                    <br/>
				<span class="thumbnail inline">
					<img src="images/help-icon2.png"/>
				</span>
                </li>
                <li><code>include_all</code>
                    Include all elements between two comments
                    or just the first and last one(might be slightly faster in some cases).
                    Default is true (include all):
                    <br/>
				<span class="thumbnail inline">
					<img src="images/help-include-all.png"/>
				</span>
                </li>

                <li><code>base</code> Optional path to documentation folder which you can use later in following
                    callbacks to return content url.
                </li>
                <li><code>section_url</code> Callback function which return a url to load the help content of a section.
                    <br/>
                    For example when a help section which refers to "basics/sidebar.compact" is requested, you can use
                    this
                    function to return the url to load which contains help content:
<pre data-language="javascript">
'section_url': function(section_name) {
	//From Ace Demo's example
   
    //according to a section_name such as `basics/navbar.toggle` return the file url which contains help content
    section_name = section_name || '';

    //for example convert section_name=`basic/navbar.layout.brand` to `basic/navbar`
    //because in Ace's documentation files 'basic/navbar.layout.brand' section is inside `basic/navbar.html` file
    var url = section_name.replace(/\..*$/g, '');

    var parts = url.split('/');
    if(parts.length == 1) {
        //for example convert `changes` to `changes/index.html`
        if(url.length == 0) url = 'intro';//or convert `empty string` to `intro/index.html`
        url = url + '/index.html';
    }
    else if(parts.length > 1) {
        //for example convert `basics/navbar.layout` to `basics/navbar.html`
        url = url + '.html';
    }
    return this.settings.base + '/docs/sections/' + url;
}
</pre>
                </li>
                <li><code>file_url</code> Similar to above callback. This function is used when a file (which contains
                    code snippets) is to be loaded.
                </li>
                <li><code>img_url</code> Similar to above callbacks. When inserting images into DOM, the url may need to
                    be updated.
                </li>

                <li><code>code_highlight</code> Used for syntax highlighting code snippets.
                    <br/>
                    Currently if Rainbow.js or Prism.js libraries are available, they will be used for highlighting.
                </li>


                <li><code>before_enable</code> Optional callback to make some changes before help is enabled.
                    <br/>
                    For example in Ace's demo, when help is enabled, we unfix navbar, sidebar, etc,
                    because when an element is fixed or is inside a fixed parent,
                    it will need a fixed help box above it and it becomes unnecessarily complex.
                </li>
                <li><code>after_enable</code> Optional callback to make some changes after help is enabled</li>
                <li><code>before_disable</code> Optional callback to make some changes before help is disabled</li>
                <li><code>after_disable</code> Optional callback to make some changes after help is disabled.
                    <br/>
                    For example in Ace's demo, we restore fixed state of previously unfixed navbar, etc.
                </li>

                <li><code>add_panels</code> Separate &amp; wrap help content inside panels like image below.
                    Default is true.
                    <br/>
				<span class="thumbnail">
					<img src="images/help-panels.png"/>
				</span>
                </li>
                <li><code>panel_content_selector</code> Use this selector to find and separate contents and wrap them
                    inside panels
                </li>
                <li><code>panel_content_title</code> Use this selector to find the title for each panel. Should come
                    before relevant 'panel_content_selector'
                </li>
            </ul>
        </div>


        <h3 class="info-title smaller">4. Example</h3>

        <div class="info-section">
            <ul class="info-list list-unstyled">
                <li>
                    For an example of using Onpage Help in your application, you can see
                    <a href="../html/index.html#help">Ace's demo pages</a>
                </li>

                <li>
                    The code that initiates help is inside
                    <code>assets/js/ace/ace.onpage-help.js</code>
                    and has comments and explanations.
                </li>

                <li>
                    For Ace's demo there is also an extra style file which is
                    <code>assets/css/ace.onpage-help.css</code>.
                    <br/>
                    It is used for styling the black help button and you don't need it.
                </li>

                <li>
                    Also, "Rainbow.js" files are include for syntax highlighting.
                    <br/>
                    You don't need them if your help content doesn't make use of it.
                </li>

                <li>
                    The help content is retrieved from <code>docs/sections</code> folder.
                </li>

                <li>
                    Inside Ace's demo, help is initiated when "#help" is appended to url and
                    a black button on right side of page is shown which enables/disables help.
                    <br/>
                    You should use your own approach.
                    <br/>
                    Perhaps a button inside navbar or sidebar which enables or disables help.
                </li>
            </ul>
        </div>


    </div>
    <!-- /section:custom/onpage-help -->

</section>